MULTICS TECHNICAL BULLETIN | MTB-125 


To: MTB Distribution 


From: T. Casey 
Date: October 2, 1974 


Subject: New list command. 


A new list command is proposed, to replace the present Iist, 
list_names, and list_totals commands. A draft MPM writeup is 
attached, and the differences between the current commands”§ and 
the proposed new command are summarized below. 


Certain changes have been previously proposed (in MTB-042) and 
approved by the MCRB. Installation of those changes has’ been 
postponed to avoid two closely spaced changes to. the user 
interface. Those changes are noted in the following summary. 


pies list_names and list_totals are eliminated, and replaced by 
the -name and -total control arguments of the list command. 


ae The -brief control argument (approved but not installed) to 
suppress printing of header lines is replaced by -no_header. 


3. The default order of listing of entry types is changed from 
segs, dirs, msfs, links, to segs, msfs, dirs, links. That 
order may be varied by the user, by typing the entry type 
control arguments in the desired order. 


4, The specification of what Is to be printed and whether or 
not to sort is separated. For example, it is possible to 
sort on one of the dates without its being printed, and vice 
versa. The -sort control argument specifies sorting. If it 
is given, the item to sort on may be specified explicitly, 


or it may be allowed to default to one of the items’ being 
printed. 


By Sorting can be done on names (approved but not fnstalled) or 
on records used, in addition to date-tIime modified and 
date-time used, 


6. All items to be printed may be spectfied explicitly by 
control arguments (-name, -record, ~-mode, -dtm, and -dtu), 
or various default combinations may be specified by a single 
control argument. [t is possIble to have both -dtu and -dtm 
printed. 


V6 The -reverse control argument does not imply. sorting by 
-dtu, as it did in the old list. It only reverses the order 
in which the list would otherwise have been printed. 
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The -short control argument (approved but not’ installed) 
eliminates extra white space during printing of 4Ilink 
pathnames. The pathnames are printed starting immediately 
after the entry names instead of being aligned in column 35. 


The -primary control argument (approved but not installed) 
specifies that additional names should not be printed (just 
the primary name). 


The -count control argument specifies that, for 
multiply-named entries, the number of names should be 
printed. 


The control arguments -segment, -file, -link, -total, -name, 
and -record will be accepted fn both the singular and plural 
form, although they will be documented only in the singular. 
This is a convenience to current users, who may be confused 
by the facts that: 


dT) in the old list command, -segment, -link, but -files 


were the accepted spellings, and the command names were 
list_names and list_totals; 


2) there presently exist control arguments -name_~ and 
~total; 


3) although most standard control arguments are singular, 
there are the following exceptions: -arguments, -files, 
-ring_brackets, and -symbols. 


The new messages printed for empty directory, starname not 
found, and no entries of specified type, will be as 
described in MTB-042. 


The two problems mentioned in MTB-042 (regarding use of 


starnames), solutions of which were postponed, will now be 
fixed: 


1) An entry will no longer be listed more than once’ when 
more than one of the given starnames matches a name on 


the entry. 


2) All names on an entry will be printed (unless -primary 
is given). (The current list command just prints those 
that match one of the given starnames. ) 


These problems are caused by deficiencies in 
hes_$star_list_. They will be solved, initially, by using 
the starname "**" jn the call to that procedure, and doing 
the star matching in an internal procedure. An external 
user-ring star matching procedure is under consideration, 
but -the interface needs more design work, and will be the 
subject of a future MTB. 
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NAME: list, Is 


The list command prints information about entries in one or more 
directories. Arguments allow the user to specify the directories 
to be listed, the entry types and entry names’ for’ which 
information is to be printed, the amount of Information to be 
printed for each entry, and the order in which the Information is 
to be printed. 


The default, when no arguments are given, is to list files 
(segments and multi-segment filles) of all names, in the working 
directory. For each entry, the mode, records used, primary name, 
and any additional names, will be printed. The two entry types 
will be listed in the order: segments, multi-segment files; 
within each entry type, entries will be printed in the reverse of 
the order in which they were created (most recently created 
first). Preceding the listing of each entry type will be a line 
giving the total number of entries of that type and the total 
records used, . 


USAGE: list -entry_names- -control_arguments- 


1) entry_names are the (optional) names of entries to be 
listed. If entry names are given, only 
entries having at least one name matching one 
of the entry names will .be listed. The star 
convention may be used in the entry names. 
Except for the -pathname control argument, 
the positions of the entry names (before, 
after, or among the control arguments) have 
no significance. 


2) control_arguments may be chosen from the following: 


-pathname dir_path 
-pn dir_path causes the directory dir_path to be searched 
for any entry names that follow dir_path on 
the command line. If no entry names’_ follow, 
then the default of ** (all entry names) will 
be used to list the directory dir_path. This 
argument may be given more than once. Any 
entry names’ preceeding its first occurrence 
refer to the working directory. (However, ** 
is mot used by default to list the working 
directory when this argument is given.) 


The following control arguments are used to specify the entry 
types to be listed: 


-segzment, -sm print information about segments. 


-multisegment_file, 
-msf print information about multi-segment files. 
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-file, -f print information about files (i.e., segments 
and multi-segment files, in that order). This 
is the default. 


=-directory, =-dr print tnformation about directories. 

-branch, -br print information about branches (f.e., 
segments, multi-segment files, and 
directories, in that order). 

-link, -1k print information about links. 

-all, -a print information about ali entry types 


(segments, multi-segment files, directories, 
and links, in that order). 


When several entry type arguments are given, the entry types will 


be listed in the order in which their corresponding control 
arguments are given. 


The following control arguments are used to specify the amount of 
information to be printed: 


-total, -tt print only the heading lines” giving total 
entries and total records used, for each 


entry type specified. 
-no_header, -nh omit the heading lines. 


-name, -nm print the heading lines, followed by the 
primary name and any additional names, for 
all selected entries. 


-record, -rec print records used, plus. all information 
printed when -name is given. 


-mode print mode, plus all information printed when 
-record is given. This is the default. 


-date_time_used, 
-dtu print date and time tast used, plus all 
information printed when -mode ts given. 


~date_time_modified, 


-dtm print date and time last modified, plus all 
information printed when -mode is given. 


If both -dtm and -dtu are given, both will be printed (dtm 
first), plus all information printed when -mode is given. 


-primary, -pri do not print’ the additional names on 
multiply-named entries. 
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-count, -ct_ for multiply~named entrfes, print the total 
number of names, after the primary name, on 
the same line. : 


-brief, -bf This argument is used to decrease the amount 
of infomation printed. Its exact effect 
depends on which other arguments are” given. 
if -total is given, then -brief will cause 
the totals information for all selected entry 
types to be abbreviated and printed on a 
single line. Otherwise, it will suppress the 
printing of records or mode when those items 
are implied but not specifically named in 
control arguments. For example, list -dtu 
-brief will cause names and date_time_used, 
but not mode and records, to be printed. 


-short, -sh | print link pathnames starting immediately 
after the entry names, instead of aligning 
them in column 35. 


The items mode, records, and date_time_used have no meaning’ for 


links, and there fs. an additional ftem, link_path, associated 
with each link. There is no control argument to specify that 
link path should be. printed. .It will be printed in all cases 
except the following: 


1) when -total is given; 


2) when -name is given; 


3) when -dtm -brief Is given; (a link has a date_tIme_modified, 
which can be sorted on and printed). 


The following control arguments’ specify the order jin_~ which 
entries will be printed, within each entry type: 


-sort sort entries according to either name, 
records, date_time_used, or 
date_time_modified, as specifed by the 
control argument immediately following -sort 
(or by the default described below). 


“name, -nm sort entries by primary name. 
-record, -rec sort entries by records used (largest first). 
-~date_time_used, 


-dtu sort entries by date_time_used (most recent 
| first). 
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~date_time_modified, 
-dtm sort entries by date_time_modified (most 
recent first). 

If one of the above four control! a 
-sort, it specifies the item to be sor ye 
the corresponding item to be printed. If none of these four 
arguments immediately follows -sort, then sorting will be done on 
the first item from the following list which jis being printed: 
date_time_modi fied, date_time_used, records, names. (For 
example, list -dtm -sort is equivalent to list -dtm -sort -dtm.) 


This has the effect of having the lIst sorted on the item in the 
leftmost column (except for mode, which is never sorted on). 


If -sort is not given, entres will be printed in the reverse of 
the order in which they were created (most recently created 
first). 


-reverse, -rv This argument is used to reverse the order in 
which entries are printed. If -sort is also 
given, the sort will be reversed. Otherwise 
entries will be printed In the order in which 
they were created (oldest first). 


